~ chicken-core (master) /manual/Egg specification format
Trap1[[tags: manual]]2[[toc:]]345== Format of the egg description file67An egg description is basically an association list holding8information about the components of the egg. An egg may contain9multiple components: libraries, programs, Scheme or C include files10and arbitrary data files. Dependencies between eggs can be11specified as can be dependencies between components of an egg.1213A list of valid properties follows.1415=== Global properties1617==== version1819 [egg property] (version STRING)2021Specifies version string for this egg. {{STRING}} should have22the format {{<MAJOR>.<MINOR>.<PATCHLEVEL>}}, where only the23{{<MAJOR>}} part is mandatory.2425Eggs from remote egg servers are automatically versioned - the26version is part of the protocol to retrieve the egg and does not27have to be specified in the {{.egg}} file. Eggs installed from28local directories (see below) should explicitly specify a version.2930==== synopsis3132 [egg property] (synopsis STRING)3334Gives a short description of this egg.3536==== author3738 [egg property] (author STRING)3940Names the author or authors of the contained code.4142==== maintainer4344 [egg property] (maintainer STRING)4546Names the maintainer of this code, if different from author(s).4748==== category4950 [egg property] (category NAME)5152Gives the category under which this egg should be contained.53See [[https://wiki.call-cc.org/chicken-projects/egg-index-5.html|the egg index]]54for a list of currently used categories.5556==== license5758 [egg property] (license STRING)5960Names the license under which this code is available.6162==== dependencies6364 [egg property] (dependencies EGG ...)6566Lists eggs that this egg depends on, and which should be67built and installed if they do not already exist in the repository.68{{EGG}} should be whether a symbol or a list of the form69{{EGGNAME VERSION}}, where the former means to install the70newest available egg with this name and the latter specifies71a specific version or higher. {{EGGNAME}} may also be the string or72symbol {{chicken}}, in case you want your extension to depend73on a minimum required CHICKEN of {{VERSION}} or newer.7475This property can also be used to specify a minimum version of CHICKEN76required by the egg. For example, to require at least CHICKEN 6.0.0:7778<enscript highlight=scheme>79(dependencies (chicken "6.0.0"))80</enscript>8182==== test-dependencies8384 [egg property] (test-dependencies EGG ...)8586Lists eggs that are required for this egg to run the tests87(if tests exist.) This only has an effect if the {{-test}}88option has been given to {{chicken-install}}.8990==== build-dependencies9192 [egg property] (build-dependencies EGG ...)9394Lists eggs that are build-time dependencies for this egg,95i.e. there are required to build, but not to run the contained96code. Currently this is treated identical to {{dependencies}}.9798==== foreign-dependencies99100 [egg property] (foreign-dependencies NAME ...)101102Lists external dependencies like native code libraries103or system-specific packages and is currently only used for104documentation purposes.105106==== platform107108 [egg property] (platform PLATFORM)109110Specifies for which platform this egg is intended. {{PLATFORM}}111should be a symbol naming the target platform ({{windows}}, {{linux}}112or {{unix}}) or a boolean combination of platform values, allowed113are {{(not PLATFORM)}}, {{(or PLATFORM ...)}} and {{(and PLATFORM ...)}}.114If the expression can not be satisfied, then installation of this115egg will abort.116117==== distribution-files118119 [egg property] (distribution-files FILE ...)120121List of files required for the installation of the egg. This122form is not handled by chicken-install, but by henrietta-cache to123determine what to cache. If the repository contains additional124files that are unneeded for the egg to be installed, you can list125all the required files in this clause to reduce the amount of data126cached by egg servers.127128==== components129130 [egg property] (components COMPONENT ...)131132Lists components (extensions, programs, include- or data files) that133this extension installs. See [[#component-types|Component types]] and134[[#component-properties|component properties]] for information on how135to specify component-specific information.136137==== host138139 [egg property] (host PROP ...)140141Recursively process {{PROP ...}}, but only for the host (build)142platform, in case this is a "cross-chicken", a CHICKEN installation143intended for cross compilation.144145==== target146147 [egg property] (target PROP ...)148149Recursively process {{PROP ...}}, but only for the target150platform, in case this is a "cross-chicken", a CHICKEN installation151intended for cross compilation.152153==== component-options154155 [egg property] (component-options OPTIONSPEC ...)156157Specifies global options for all programs and extensions compiled for this egg.158{{OPTIONSPEC}} may be {{csc-options}}, {{link-options}} or {{linkage}} specifications.159160==== cond-expand161162 [egg property] (cond-expand CLAUSE ...)163164Conditionally expand egg specification forms, depending on system165features. Each {{CLAUSE}} should be of the form166{{(TEST PROPERTY)}} where {{TEST}} is a feature identifier or a167conditional form, in the same syntax as used in the {{cond-expand}}168syntactic form.169170In addition to normal system-wide feature identifiers, feature identifiers171given via the {{-feature}} option to {{chicken-install}} are visible in172the tests. Also, the features {{target}}, {{host}}, {{dynamic}} and173{{static}} are visible, depending on surrounding egg specification174forms for constraining mode and linkage.175176==== error177178 [egg property] (error STRING ARG ...)179180Signal an error and abort processing. Mostly useful inside {{cond-expand}} forms.181182==== custom-build183184 [egg property] (custom-build STRING)185186Specifies a custom build script to be invoked for all components of the egg,187ignoring all component-specific instructions and properties. {{STRING}} should be the188name of a {{sh(1)}} shell script and thus may be platform189sensitive. The path to the file is prepended implicitly, so you190should '''not''' prefix it with {{./}}.191192The script is executed with the location of the CHICKEN193binaries in the {{PATH}}. Also, the following environment variables194are set in the execution environment of the script:195196* {{CHICKEN_CC}}: name of the C compiler used for building CHICKEN197* {{CHICKEN_CXX}}: name of the C++ compiler set during the build of CHICKEN198* {{CHICKEN_CSC}}: path to {{csc}}199* {{CHICKEN_CSI}}: path to {{csi}}200201=== Component types202203==== extension204205 [egg property] (extension NAME PROP ...)206207Specifies an extension library component. The properties208{{PROP...}} are processed recursively and apply only to this209component.210211==== data212213 [egg property] (data NAME PROP ...)214215Specifies one or more arbitrary data files.216217==== generated-source-file218219 [egg property] (generated-source-file NAME PROP ...)220221Specifies a file that is generated during the process of building222the egg.223224==== c-include225226 [egg property] (c-include NAME PROP ...)227228Specifies one or more C include files.229230==== scheme-include231232 [egg property] (scheme-include NAME PROP ...)233234Specifies one or more Scheme include files.235236==== program237238 [egg property] (program NAME PROP ...)239240Specifies an executable program.241242==== c-object243244 [egg property] (c-object NAME PROP ...)245246Specifies a compiled C/C++ object file. Usually this component type247is required if you want to link a separately compiled C/C++ module248with your extension or program. C-objects are compiled like Scheme249source files with the {{csc}} tool to ensure the same C compiler250options and toolchain is used as for regular Scheme files compiled251to C. If you want to pass compiler-specific options to the build252of the C object, use the {{csc-options}} property and precede253C compiler options with {{-C}}.254255Components of this type are never installed, they just exist at build time.256257==== installed-c-object258259 [egg property] (installed-c-object NAME PROP ...)260261Similar to {{c-object}}, but the compiled object file will be installed in the262extension repository.263264=== Component properties265266==== host267268 [egg property] (host PROP ...)269270Process {{PROP ...}} recursively for the current component, but271apply the properties only to the host (build) part, when using272a CHICKEN installation intended for cross-compilation.273274==== target275276 [egg property] (target PROP ...)277278Process {{PROP ...}} recursively for the current component, but279apply the properties only to the target part, when using280a CHICKEN installation intended for cross-compilation.281282==== linkage283284 [egg property] (linkage LINKAGE)285286Define whether the component should be linked dynamically or287statically. {{LINKAGE}} can be {{static}} or {{dynamic}}. This288property only makes sense for extension libraries.289290==== types-file291292 [egg property] (types-file [NAME])293294Specifies that a "type-database" file should be generated and295installed for this component. This property is only used for296extension libraries. The name is optional and defaults to the297name of the extensions (with the proper extension).298299If {{NAME}} is a list of the form {{(predefined [NAME])}}, then300no types file is created during compilation and an existing types file301for this extension is assumed and installed.302303==== inline-file304305 [egg property] (inline-file [NAME])306307Specifies that an "inline" file should be generated and installed308for this component. This property is only used for extension309libraries. The name is optional and defaults to the310name of the extensions (with the proper extension).311312==== custom-build313314 [egg property] (custom-build STRING)315316Specifies a custom build script that should be executed instead of317the default build operations for this component. This property is mandatory for318components of type {{generated-source-file}}.319{{STRING}} should be the320name of a {{sh(1)}} shell script and thus may be platform321sensitive. The path to the file is prepended implicitly, so you322should '''not''' prefix it with {{./}}.323324The script will be invoked like the {{csc}} program and325is executed with the location of the CHICKEN326binaries in the {{PATH}}. Environment variables are set up as327for the global {{custom-build}} property, as described above.328329==== csc-options330331 [egg property] (csc-options OPTION ...)332333Specifies additional compiler options for {{csc}} that should be334used when building this component. If this property is not335given, the default options are used, which are {{-O2 -d1}}336for extensions and programs and {{-O2 -d0}} for import337libraries.338339Note that the options are quoted when passed to csc during the340compilation of the extension, so multiple options should be specified341as {{(csc-options "OPT1" "OPT2" ...)}} instead of {{(csc-options "OPT1 OPT2")}}342(the latter would be a single option containing a whitespace character).343344OPTION may optionally be a list of the form {{(custom-config FILENAME ARG ...)}},345which allows to dynamically determine options to be passed to the {{csc}}346program. FILENAME should be the name of a Scheme source file in the347current build directory. The file is invoked as {{csi -s FILENAME ARG ...}}348and should write s-expressions to stdout that are taken as additional349options to be passed to {{csc}} when compiling a component. The expressions350are read in, any list structure is flattened and all items are converted to351strings and added to the list of compilation options.352353==== link-options354355 [egg property] (link-options OPTION ...)356357Specifies additional link options for {{csc}} that should be358used when building this component.359360Note that the options are quoted when passed to csc during the361compilation of the extension, so multiple options should be specified362as {{(link-options "OPT1" "OPT2" ...)}} instead of {{(link-options "OPT1 OPT2")}}363(the latter would be a single option containing a whitespace character).364365Note that in order to pass linker options to the underlying C-compiler, these must366be prefixed with {{-L}}, eg. {{(link-options "-L" "-lpng")}}.367368This property supports {{custom-config}} specifications, described above.369370==== source371372 [egg property] (source NAME)373374Specifies an alternative source file, in case it has a name375distinct from the component name. By default the source file376for a component is named after the component, with the {{.scm}}377extension added.378379==== install-name380381 [egg property] (install-name NAME)382383Specifies an alternative installation name of the component,384if it differs from the actual component name. This property385is most useful if an egg installs an extension and a program386of the same name, but needs to distinguish the components during387build time.388389==== component-dependencies390391 [egg property] (component-dependencies NAME ...)392393Specifies dependencies to other components. {{NAME ...}} must394be the names of extension, program, scheme-include- or generated source file395components that should be built before the current component.396397==== source-dependencies398399 [egg property] (source-dependencies NAME ...)400401Specifies dependencies to additional source files. {{NAME ...}} must402denote filenames of which the program or extension depends.403A program or extension implicitly depends on its source file and404and on the egg-specification file.405406==== objects407408 [egg property] (objects NAME ...)409410Specifies that the components of type {{c-object}} should be linked411to this component and that the object components are dependencies.412413414==== destination415416 [egg property] (destination NAME)417418Specifies an alternative installation destination for the419built component and only applies420to components of type {{data}}, {{c-include}} and {{scheme-include}}.421This property should only be used in extreme422cases, as it is recommended to use the default installation423locations, which are:424425* for C include files: {{<PREFIX>/include/chicken/}}426427* for Scheme include files: {{<PREFIX>/share/chicken/}}428429* for data files: {{<PREFIX>/share/chicken/}}430431==== files432433 [egg property] (files NAME ...)434435Specifies source files for this component and only applies436to components of type {{data}}, {{c-include}} and {{scheme-include}}.437Both files and directories may be given and parent directories438are created as needed.439440==== modules441442 [egg property] (modules NAME ...)443444Specifies modules that the component (usually an extension) contains.445{{chicken-install}} will compile and install all import libraries for the given modules.446If this property is not given, then it is assumed that the extension has a single447module of the same name as the component.448449==== cond-expand450451 [egg property] (cond-expand CLAUSE ...)452453Similar to the toplevel {{cond-expand}} clause and may appear inside454component specifications.455456==== error457458 [egg property] (error STRING ARG ...)459460Similar to the toplevel {{error}} form, may appear inside component specifications.461462---463464Previous: [[Extension tools]]465466Next: [[Units and linking model]]